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REVIEW AND APPROVAL 



This technical report has been reviewed and is approved. 



CHARLES E. MCKUSICK, Lt Colonel, USAF 

Chief, Systems Analysis Division 

Directorate of Systems Design and Development 



ii 



ABSTRACT 



GRASP is a set cC PL/I compatible subroutines which provide 
programming support for the IBM 2260 Display Station in local 
attachment; i.e., the attachment of a 2260 directly to a System/ 
360 CPU channel via the IBM 2848 Display Control. The subroutines 
are coded in OS/360 Assembler Language and are reentrant. They 
permit the PL/I programmer to manipulate the 2260 as an I/O device 
in the same manner available to the Assembler Language programmer 
using the Graphics Access Method under OS/360 (with restrictions 
as noted in the Introduction to Voltjune I of this document) . All 
errors, except those which normally result in OS/360 abnormal ends 
(abends) , are returned to the user via subroutine parameters. 
GRASP is designed to operate under the MFT configuration of OS/360. 

Volume I of this document gives an overview of the 2260 and 
an introduction to the GRASP routines. Volume II gives detailed 
program specifications. 
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SECTION I 
INTRODUCTION 



The IBM 2260 Display Station is a small character-oriented dis- 
play which may be attached to an IBM System/360 computer via trans- 
mission lines to an IBM 2701 Data Adapter Unit (remote attachment) 
or directly to a CPU channel via the IBM 2848 Display Control Unit 
(local attachment) . Progranmiing support for the former mode of 
attachment is provided to Assembler Language programmers under OS/360 
via the Basic or Queued Telecommunications Access Methods (BTAM and 
QTAM) . Programming support for the latter mode, also available only 
to Assembler Language programmers, is provided by the Graphics Access 
Method (GAM) . At the time of this writing IBM does not support either 
mode of attachment in any of its available higher level languages, 
although QTAM support has been announced for PL/I Version 5, to be 
released in early 1970. 

For some time, two 2260' s in local attachment (and therefore 
supported by GAM) were available at MITRE, although until early 1969 
there was much interest but little use. Wi-h the advent of IBM's 
Conversational Programming System (CPS) and interest in the 2260 's 
by the MITRE Management Information System (MIS) and Military Air- 
lift Command (MAC) projects, use of the 2260 's increased. A need 
was immediately felt for an interface to GAM for the PL/I Language, 
since both the MIS and MAC projects were using that language. 

A preliminary investigation of available software was under- 
taken by the MIS project and revealed that there was no interface 
package available at the time which reflected, on the one hand, 
the inherent simplicity of the GAM support and the 2260 itself and 
which, on the other hand, did not inhibit the higher level language 
programmer from taking full advantage of the capabilities available 
to the Assembler Language programmer using GAM. In addition, since 
the PL/I Language already provided certain basic system programming 
capabilities, foremost among these being the capability of producing 
reentrant programs, it was felt that the interface package should be 
reentrant. This would guarantee in addition that the package could 
ho transferred to a computing system using MVT, without degrading 
cnat system's capabilities and without reprogramming. A suitable 
interface package not being found, it was decided to build such a 
package at MITRE; that package is GRASP. 



The version of GRASP documented in this paper does not provide 
the full capability of GAM programming support. It supports: 

(1) I/O operations addressing a 2260; 

(2) the keyboard and line addressing features of the 2848; and 

(3) attention handling in a background-type user program via 
the *'basic** method (see reference 2) • 

GRASP does not support: 

(1) user written asyncijroivous attention processing programs; and 

(2) the **express*' method of attention handling (see reference 2) . 

In addition, although GRASP was written to support any valid 2848/ 
2260 combination, it has only been tested with a 2848 Model 3 with 
two attached 2260 Model 1 Display Stations. The omission of the 
express attention handling capability is not serious since it does 
not appear to be as useful as the basic method, and if it were re- 
quired, it could be provided with a minimum of effort. However, the 
omission of support for user written asynchronous attention processing 
programs is significant. Considerable work was done to determine if 
it would be possible to Implement a PL/l programmer- defined condition 
which would be raised whenever an attention occurred. The PL/I pro- 
grammer would then be able to use the full capabilities of PL/l for 
enabling and disabling condition handling specifications. But it 
was found that the manner in which asynchronous exit routines are 
activated by the Operating System is not compatible with the PL/I 
implementation of condition on-units. One method of interfacing the 
Operating System and PL/l was Identified, but it required the addition 
of a special SVC routine to the system library. This was felt to be 
an unsatisfactory approach to the problem, and the attempt to imple- 
ment this capability was abandoned. 

This paper is divided into two volumes. The first gives a brief 
introduction to the 2260, and describes GRASP and its use. The second 
gives detailed specifications of the GRASP routines. The reader is 
assumed to be familiar with the PL/l Language. 



SECTION II 
THE 2260 ENVIRONMENT 



GENERAL DESCRIPTION 

This section presents a subset of information from selected 
documents in the Bibliography. Readers desiring more information 
should consult the appropriate document. 

The 2260 is a small character-oriented display capable of dis- 
playing either 6 or 12 lines of either 40 or 80 characters each, 
depending on the 2260/2848 configuration (see Figure 1) . The range 
of characters includes: 

26 alphabetic characters; 

10 numeric characters; 

25 special symbols (including the space and new line 
symbols) ; and 

3 control symbols (cursor, check and start symbols) , 

Graphics associated with the special and control symbols are shown 
in Figure 2. Bit patterns for all symbols displayable on a 2260 
Display Station are shown in Reference 3. Operating instructions 
for the 2260 Display Station can be found in Reference 1, 



SPECIAL FEATURES 

Special features of 2848/2260 configuration of interest to the 
user of GRASP include the keyboard, line addressing, non-destructive 
cursor, data entry, and 1053 Printer options. Other special features 
are available and are described in Reference 3. 

Keyboard 

If the selected 2260 is not equipped with the keyboard feature, 
the parts of the GRASP package dealing with attention handling and 
input operations must not be used. Such a 2260 is only an output 
device. 
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Figure 2. Special and Control Symbols 



The CPU is interrupted via the ENTER key on the keyboard attached 
to a 2260, causing the control program to store information related to 
the attention in an attention queue. Via the attention handling capa- 
bilities of GRASP, the programmer may inspect the attention queue and 
service the device. 

Line Addressing 

This feature permits the prograimer to specify, via a control 
character transmitted to the 2260 as the first byte of data to be 
written, that display is to begin at column 1 of a particular line 
of the screen. This feature also permits a very limited cursor 
positioning capability: if only the control character is transmitted, 
the cursor is positioned to column 1 of the indicated display line. 

Non-Destructive Cursor 

The statidard destructive cv.rser is a symbol, indistinguishable 
from the EOM symbol, which indicates the display position to be 
occupied by the next character key depressed or character displayed. 
It occupies a display position and overwrites display positions as 
it advances. The non-destructive cursor performs the same function 
as the destructive cursor, but is a different graphic and does not 
occupy a display position; it is displayed to the left of and slightly 
below the next character position to be filled when data is trans- 
mitted or when a character key is depressed. 

Data Entry 

After the completion of a read operation from a 2260, the key- 
board of the selected 2260 is mechanically unlocked and operator 
entry may resume. The data entry models of the 2848 Display Control 
permit the bypassing of this operation, thereby enabling program 
verification and response to operator input prior to the entry of 
another message. This is supported in GRASP by the "lock" (L) code 
in the mode arguments to the read, write, and erase routines. If 
the 2848 controlling the selected 2260 is not a data entry model, 
these codes must not be used. The data entry models of the 2848 
have several other features, including a keypunch-type keyboard 
layout (rather than a typewriter layout) , which are described in 
Reference 3. 



Printer 

A 2848/2260 configuration can be equipped with a slave 1033 
printer. This is a low speed (14 characters per second) modified 
SELECTRIC printer and may either be activated by the operator via 
the PRINT key on the 2260 or be treated as an output device by the 
computer program. Programming considerations for the 1053 printer 
are given In References 2 and 3. 



SECTION III 
GRASP/2260 USER'S MANUAL 



INTRODUCTION 

GRASP is a set of subroutines and functions which provide the 
PL/I programmer programming support for the 2260 Display Station. 
The subroutines available can be broken down into the following 
categories: 

• General I/O Support - this group includes subroutines 
which allocate and format graphics control blocks, and 
perform the open and close functions. 

• Specific I/O Routin^^s - this group includes routines 
which initiate read, write, and erase operations to a 
2260, and which wait for the completion of I/O opera- 
tions. 

• Attention Handling - this group includes subroutines 
which allocate and build attention environment control 
blocks, and which support the inspection of the Opera- 
ting System attention queue. 

• Support Functions - this group includes a set of func- 
tions which, among other things, permit the PL/I pro- 
grammer to access information in graphics control blocks. 

Figure 3 lists the GRASP routines under the above headings and 
gives a brief definition of each. 

This section describes the use and features of the GRASP routines. 
Control blocks of interest to the GRASP user are described as back- 
ground information. The input and output routines are then described, 
followed by a discussion of attention processing. Several special 
programming considerations are presented and a final section describes 
a sample GRASP application. 



General I/O Support 

GQPEN - Define and open a graphics data control block. 

GCLOSE - Close a graphics data control block. 
Specific I/O Routines 

GREAD - Initiate a read from a 2260. 

GWRITE - Initiate a vrite to a 2260. 

GERASE - Initiate an erase of a 2260. 

GWAIT - Wait for the completion of an I/O operation. 
Attention Handling 

GAAP - Activate attention processing. 

GDAP - Deactivate attention processing. 

GAQ - Attention inquiry. 
Support Functions 

GNUNITS - Number of units in a unit group. 

GUNIT - Unit in the unit group causing an attention. 

GLINENO - Line number conversion. 

GNCP - Number of channel programs value. 



Figure 3. GRASP Routines 



CONTROL BLOCKS 

The GRASP user is required to be familiar with three OS/360 
I/O control blocks: the Data Control Block, the Graphics Attention 
Control Block, and the Data Event Control Block. This section de- 
scribes these control blocks and their use by GRASP routines. 

The user is not expected to know the format of these control 
blocks. Each control block is automatically generated by an appro- 
priate GRASP routine and its address is returned to the user as a 
PL/I POINTER variable. This variable is then passed as an argument 
to other GRASP routines which require access to the particular con- 
trol block. 

Data Control Block (DCB) 

The DCB is the primary link between the external device and 
other I/O control blocks. It is generated by the open process by 
a call to the GOPEN routine, is specified in calls to GREAD, GWRITE , 
and GERASE to initiate I/O operations, and is referenced in the call 
to GCLOSE to perform the close process. It is also used as an argu- 
ment to the GAAP routine (Activate Attention Processing) to initiate 
attention handling operations (see below). 

Graphics Attention Control Block (GACB) 

A GACB is generated for each DCB for which attentions are to be 
processed. The GACB is generated by the GAAP subroutine, is specified 
as an argument to the GAQ (Attention Inquiry) routine to inspect the 
attention queue, and is input to the GDAP (Deactivate Attention Pro- 
cessing) routine to terminate the processing of attentions for a 
specific DCB. Since attention processing is always DCB-specific, 
the pointer to the DCB must be specified as an argument to the GAAP 
routine. Thereafter, only the GACB need be specified since it con- 
tains an internal pointer to the DCB with which it is associated. 

Data Event Control Block (DECB) 

The DECB is exactly equivalent in function to a PL/l EVENT 
variable. A unique DECB is generated each time a call is made to 
GREAD, GWRITE, or GERASE to initiate an l/O operation, and its 
address is returned as a PL/I POINTER variable. This pointer may 
then be specified as an argument to the GWAIT routine to wait for 
completion of the associated l/O operation. 
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INPUT OPERATIONS 

Three types of input operations are provided to the user of 
GRASP: buffer input, manual input, and short manual input. All 
three types are implemented by options of the GREAD routine. 

Buffer Input 

If 'B' is coded as the read-mode argument to the GREAD routine*, 
the entire contents of the buffer of the selected 2260 Display Sta- 
tion is transferred to memory. After transfer, the screen is erased. 
All characters, including special characters, are transferred. 

Manual Input 

If 'M' is coded as the read-mode argument to the GREAD routine, 
the characters on the screen between the START symbol (► ) and the 
EOM symbol (m) are transferred to memory. The START symbol is 
deleted from the screen and the cursor is placed immediately to the 
right of the position originally occupied by the START symbol. 

The new line s3mibol (^) has a special use with manual input 
read operations. When a new line symbol is encountered between the 
START and EOM symbols during the read operation, characters on the 
same line as and to the right of the new line symbol are skipped 
and data transfer begins again with the first character on the next 
line. The new line symbol is transferred as a data character. 

The behavior of the manual input read operation on encountering 
a new line symbol can be used to advantage when more than one dis- 
tinct piece of information is to be transferred in a single read 
operation. Consider an example. The program initially displays 
command information on the right of the screen and places the cur- 
sor at column 1 of the first line: 

. JOB NAME 

' PROJECT NO. 

DEPT. 



Detailed definitions of the arguments to GRASP routines are 
given in Volume II of this document. 
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The display operator enters the START symbol and the "job name" and 
depresses the new line key. This causes the cursor to move to 
column 1 of the second line: 





TESTJ 


JOB NAME 
PROJECT NO. 


1 




DEPT. 



The operator continues by typing the other required information and 
depresses the ENTER key when the message is complete: 



► TEST J 


JOB NAME 


512A^ 


PROJECT NO 


D73'B, 


DEPT. 



When the program issues a manual input read operation, the string 
transferred is: 

•test d 512A d D73'. 

Transfer of input data to the string variable specified in the 
call to GREAD occurs asynchronously to the execution of the user's 
program. In addition, the current length of this string variable, 
which has the VARYING attribute, is not set until a GWAIT is issued 
for the read operation. For these reasons, it is advisable not to 
make reference to the string variable until after the operation is 
complete; i.e., after a call has been made to GWAIT. 

Short Manual Input 

At the completion of a manual input operation, the START symbol 
is deleted from the screen and the cursor is placed to the left of 
the position originally occupied by the START symbol. Short manual 
input, identical to manual input in all other respects, does not 
delete the START symbol from the screen and therefore results in a 
somewhat faster read operation. 
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OUTPUT OPERATIONS 

Three types of output operations are provided by GRASP: screen 
erase, buffer output, and line addressed output. The screen erase 
operation is provided by the GERASE routine. The reinaining two write 
operations are performed by the GWRITE routine. 

Screen Erase 

Two methods are available for erasing the screen of a 2260, The 
first method, used when a write operation will not immediately follow 
the erase, is provided by the GERASE routine. The second method is 
the pre-write erase option of the GWRITE routine. In this case, the 
screen is erased immediately prior to the write operation specified 
by the call to GWRITE. 

Buffer Output 

By coding 'B' or 'EB' (if a pre-write erase is desired) as the 
write-mode argument to the GWRITE routine, the programmer may specify 
that the specified string argument is to replace the contents of the 
buffer of the selected 2260 Display Station. If this mode is used, 
the length of the string to be displayed must be exactly equal to the 
size of the buffer for the selected 2260 Display Station (either 240, 
480 or 960 characters, depending upon the 2848 model in use). 

The first character of the string to be displayed appears in 
column 1 of the first display line, and subsequent characters are 
displayed adjacent and to the right with spillover to subsequent 
display lines . 

Line Addressed Output 

When a 2848/2260 combination is equipped with the line addressing 
feature, the programmer may specify that a message is to be displayea 
on a particular line of the selected 2260 Display Station. This type 
of write operation is specified by coding 'A' or 'EA' (if a prc-writc 
erase is desired) as the write-mode argument of the GWRITF routine. 

In this mode of operation, the first byte of data is interpreted 
as a control character, indicating the display line to which the 
string will be written. This character must be included in the length 
of the string, but is not displayed. Display of the string begins at 
column 1 of the addressed line and spills over to subsequent lines 
(with wrap around from the last line to the first line) if the string 
is longer than one display line. Characters on the screen beyond the 
last character of the displayed string are not affected by a line 
addressed write operation. 
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A special function, called GLINENO, is provided as a part of 
GRASP to aid the user of line addressed output. The user specifies 
the desired line number as a FIXED BIN (31) integer, and codes the 
following expression as the string argument to the GWRITE routine: 

GLINENO(line_number) | | string 

where "string" is the string to be displayed. The returned value 
of the GLINENO function has the attribute CHAR(l). The duiiiny argu- 
ment generated by PL/l for the string expression above automatically 
accounts for the addition of the control character to the string to 
be displayed. 



ATTENTION HANDLING 

Attention handling support is provided in GRASP by the GAAP, 
GAQ and GDAP routines . This section describes these routines and 
their use. 

Initialization 

To initiate attention processing the user calls the GAAP routine 
specifying the DCB for which attentions are to be accepted. GAAP 
generates a GACB, notifies the control program that attentions for 
that DCB/GACB combination are to be honored, and returns the GACB 
address to the user. Any attentions occurring after the call to 
GAAP are queued by the control program until the user calls GAQ 
to inspect the queue. 

Attention Inquiry 

Whenever the user wishes to inspect the attention queue, he 
calls the GAQ routine, passing as an argument the GACB associated 
with the DCB for which attentions are desired. He also specifies, 
via an argument, the mode of the query: 

(1) Wait (W) or Relinquish (R) mode'*?; 

(2) Conditional (C) mode; and 

(3) Clear (X) mode. 



Wait and Relinquish modes are equivalent in this implementation 
of GRASP. They are included for compatibility vith possible 
future extensions of GRASP. 
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In W-mode or R-mode, the user is placed in a wait state until 
the desired attention occurs. In C-mode, the user requests that a 
BIT(l) variable specified as an argument be set to '1*B or *0*B to 
indicate whether or not the desired attention is present. If X- 
mode is specified, the attention queue is cleared; any attentions 
on the queue are lost. 

The user selects a desired attention by spec:' fying as an argu- 
ment the unit number of the 2260 Display Station for which attentions 
are expected. This number, meaningless for X-mode, may be an integer 
greater than or equal to 1 to select an attention from a particular 
2260 or may be zero to indicate that attentions are to be accepted 
from any 2260 defined by the DCB associated with the specified GACB. 

On return from an R-mode or W-mode call to GAQ, the desired 
attention is present and a GREAD may be issued to the unit causing 
the attention. Similarly, on return from a C-mode call, if the 
BIT(l) variable has been set to *1*B the attention is present and 
a read may be issued. 

If for C-mode, R-mode, or W-mode, a non-zero unit number was 
specified, the user knows which unit caused the attention, and a 
read may be issued to that particular unit by specifying the same 
unit number in the call to GREAD. If, however, zero was specified 
as the unit number to indicate that attentions are to be accepted 
from any device, the user needs to know which of the devices defined 
by the GACB/DCB combination caused the attention. For this purpose, 
a GRASP routine, called GUNIT, is provided. On return from GAQ, 
and in the presence of an attention, the function returns the unit 
number of the unit causing that attention. 

Termination 

To terminate the processing of attentions, the GRASP user calls 
the GDAP routine. This program notifies the control program that 
queueing of attention information for the DCB associated with the 
specified GACB should cease; storage occupied by the GACB is freed. 
Any attentions occurring after the call to GDAP are lost. 
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SPECIAL CONSIDERATIONS 

The Number of Channel Programs (NCP) Parameter 

It is possible, when servicing more than one 2260 using a 
single Data Control Block (DCB) (and therefore a single Data 
Definition (DD) stateraentX to overlap I/O operations on these 
devices. The NCP parameter of the DCB may be used for this pur- 
pose. The function of NCP is to specify to OS/360 the maximum 
number of channel programs; i.e., I/O operations, which may be 
outstanding for a given DCB at any time. Outstanding I/O opera- 
tions are ones which have been initiated (in GRASP by a call to 
GREAD, GWRITE, or GERASE) for the same DCB without an intervening 
wait operation (performed in GRASP by calling GWAIT) . 

The value of NCP is an integer between 1 and some maximum 
value specified during system generation of the OS/360 version 
in control, but is never greater than 99. The value of NCP for 
a particular DCB may be specified by the programmer in his call 
to GOPEN or may be specified on the DD statement by coding 
DCB==GNCP=value. If the NCP value is specified in the call to 
GOPEN, this value overrides any value specified on the DD state- 
ment . 

In a GRASP application where more than one 2260 is defined 
by a single DCB, the progranmer may set the NCP value for the 
DCB to a value high enough to permit simultaneous I/O operations 
to be in effect for all of the 2260 's defined by the DCB. By 
calling the GNUNITS routine prior to opening the DCB, the pro- 
gram determines the number of devices defined on the DD state- 
ment for the DCB. The programmer may then set the NCP argument 
to GOPEN to this value. This allows the GRASP program to exer- 
cise a certain measure of control over the external specification 
of the NCP value, while at the same time not restricting the pro- 
gram to a particular, perhaps too small, value. 

The following rules must be followed in making use of the 
NCP capability for overlapping I/O operations: 

(1) Every overlapped I/O operation must have its 
own DECB. This is accomplished by using 
unique identifiers for the first arguments 
("decbptr") in overlapped calls to the I/O 
initiation routines (GREAD, GERASE, and 
GWRITE) . 
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(2) I/O operations must be waited on (by 
calling GWAIT) in the order in vhich 
they were initiated. For example, 

CALL GREAD (DECBl, . . .) 

GALL GREAD (DECB2, ...) 

GALL GWAIT (DECB2,...) 

GALL GWAIT (DECBl,.. .) 

is not correct; the waits must be per- 
formed in the opposite order. 

WritinR the START Symbol 

The START and EOM symbols are used to identify the characters 
in the buffer to be transmitted to memory on a manual input read 
operation. Both symbols may be entered on the screen by the dis- 
play operator. It is, however, desirable under certain circumstances 
for the user program to display the START symbol as part of a command. 
Ihe program might display: 

"ENTER NAME ► " 

where "►" represents the START symbol. The cursor would appear 
immediately to the right of the START symbol. The operator of the 
display would then follow by typing his name and depressing the 
ENTER key. The displaying of the START symbol by the program can 
result in a significant increase in "throughput", especially when 
operator responses are short. 

Since the START symbol corresponds to the graphic "^ ", which 
is generally not available on print trains, a CHAR(l) string 
variable, GCENT, the value of which is this symbol, is available 
to the user of the GRASP standard include set (see "Sample GRASP 
Application"). If the user wishes to include the START symbol 
in his displayed string, he simply concatenates the variable GCENT 
to the string he wants displayed. In the above example, the string 
argument to the call to GWRITE which resulted in the above message 
being displayed would have been coded: 

'ENTER NAME 'I | GCENT 
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Using Line Addressed Output 

Care must be taken when using line addressed output to "clean 
up" areas of the screen affected by previous operator messages. 
Consider the example in section a of Figure 4. The call to GWRITE 
causes the message 

ENTER NAME ^ 

to be displayed on line 1 of the display. The cursor is shown to 
the immediate right of the START symbol to indicate that the first 
character key to be depressed by the display operator will cause 
that character to appear adjacent to and to the right of the START 
symbol . 

The display operator then types in his name and depresses the 
ENTER key causing the EOM symbol to appear. The first line of the 
.lisp Lay would now contain: 

ENTER NAME ► R. H. BULLEN - 

When the GREAD subroutine is called* the characters between the START 
and EOM symbols are transferred to memory and stored in the program 
variable "NAME" and the display line is automatically modified to 
contain: 

ENTER NAME R. H. BULLEN ■ 

I 

A branch is now taken to the statement labelled "LOOP", causing the 
command to be rewritten, and the display line to appear as: 

ENTER NAME K R. H. BULLEN ,■ 
I 
The previous operator input remains on the screen since the command 
is output using line addressing. 

One way of solving this problem is shown in section b of Figure 
4. By adding an extra call to GWRITE, the first line of the display 
is blanked out prior to writing the command. It is necessary to use 
two separate calls to ensure that the cursor will appear Immediately 
to the right of the START symbol, when the command is displayed. 
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a) LOOP: GALL GWRITE (..,, 'A* ,,.. ,GLINEN0(1) | | 'ENTER NAME ' | |gCENT, ...) ; 

CALL GREAD ( . , . , 'M* , . . . ,NAME, . . .) ; 

GO TO LOOP: 

b) L00P2: CALL GWRITE ( . , . ,GLINEN0(1) | | (80) ' *,...); 

GALL GWRITE ( . . . ,GLINEN0(1) | | 'ENTER NAME'j [gCENT, . . . ) ; 
GALL GREAD (.. ,NAME,...); 
GO TO L00P2; 

Figure 4. A Line-Addressed Output Example 
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SAMPLE GRASP APPLICATION 

Figure 5 shows the PL/I source language for a sample GRASP 
application. In general, the program initializes a display and 
waits for attentions. When an attention occurs, a read is issued 
and the string received is printed. When the operator at the dis- 
play enters "STOP", the program erases the display and terminates. 

Several points are worth noting about the program: 

(1) In the compile step, a DD statement defining 
the include library AAINC is required, if the 
GRASP standard include set is used. The in- 
clude set is shown in Figure 6 and contains 
declarations for the GRASP routines and the 
definition of the special variable GCENT, the 
value of which appears as the START symbol 
when displayed on a 2260. 

(2) A 7o INCLUDE statement is required to cause 
the GRASP program declarations to be in- 
serted in the program. Tlie statements which 
follow the % INCLUDE cause selected declara- 
tions to be inserted in the program as source 
code. The specific declarations are selected 
by coding the name of the desired subroutine 
followed by a # sign; for example, GOPEN# is 
coded to cause the declaration of the GOPEN 
routine to be inserted in the program. Each 
subroutine declaration selection must be 
followed by a semicolon. Figure 7 shows 

the listing of the PL/I compilation of the 
sample program, indicating the inclusion 
of the selected declarations. In addition 
to the individual declarations, a special 
symbol GALL# is provided which, when in- 
cluded in the user's program, results in 
the inclusion of declarations for all GRASP 
routines . 

(3) Hie third argument to the GOPEN routine is 
coded as 'lOE' to indicate that the GREAD, 
GWRITE, and GERASE routines will be used. 
The NCP value is set to 1. 
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000000 0001 11 HI 111 122222 222 2 23333 3333 SB^^^^f'r^f^A^^fS 5555 555556666666666 7777777 7778 

//DISPLAY JOB ( •512A»,073f 10,0082) I 'BULLEN RH«,CLASS-0 
// tXEC PL1LFCLG,PARM.PL1L='M» 

//PI IL.DC.LS DD DSN=AAlNCfDISP=SHR,UNIT=PACK, 
// vaL=(PRIVATEf RETAIN,SeR=DP5010) 

//PLIL .SYSIN no * 
DISPLAY : PROC UPT IUNS( MA IN ) ; 

DCL (DCBPTR,GACBPTR,DtCBPTR ) POINTERi 

CUND BIT( l)f 
MIMSG CHAR(30) VAKYING, 
R FIXED tilN(31) ; 
% INCLUDE DCLS (GRASP INC); 
GUPEN»; 
GAAP/f ; 
GWRITE/^: 
GWAIT#; 
GL INENO^; 
GAO)l^: 
GREAD*; 
GERASE^ : 
GDAP/^; 
GCLOSE#; 
GCENT^; 
CALL GOPEN (DC BPTR i • DI SP • , • lOE • , • BASI C • i 1 t 0,R) ; 
CALL GAAP (GACBPTR,OCBPTR,R) : 

LOOP : CALL GWK I IE ( DtCBP TR , • E A • ,0C6PTR , 

GLINENO( 1)11 •READY • I I GCENT, 1 , R ) ; 
CALL GWAIT (OECBPTR.R) ; 
CALL GAC (GACBPTRi •WSCOND, 1»R) ; 

CALL GREAD (DECBPTR, 'M • , 0C8PTR t M IMSG » I ,R) ; 
CALL GWAir (OECBPTR.R) ; 
PUT EDIT (MIMSG) (SKIP, A); 

IF MIMSG-.= 'STOP» THEN GO TO LOOP; 
CALL GERASE ( DECBPTR ,••, DCBPTR , 1 .R ) ; 
CALL GWAIT (DECBPTR, R) ; 
CALL GDAP (GACBPTR.R) ; 

CALL GCLOSE (DCBPTR); 
END; 
/♦ 

//LKED.SYSLIB DD DISP=SHR 

// 00 DSN=AAL IB,DI$P=SHR,UNIT*PACK, 

// VCL=( PRIVATE, RETA IN, SER^DP5010) 

//GG.DISP DD UNIT=0ISPLAY 



000000000111111 HI 122222222 2233333333334444<f<f4444555 5555 55566666666667 7777777 7 78 
1 2 3^5 6 7890 12 3456 78901 23^567 890 12 3<f567a9012 3456789012 3<f56 78 901 23^5678901 2 ?.-S67 8^3 

Figure 5. 
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Gb^ASP SMNQARD JMCLUDE SET ; AAl NC ( GRASP I .>JC > 
:C001 li 11 11 11 1^2222^:22 223i333333334H44444444555555555 56606ft66666 777777777 78 



r 
-I 



t 



DCi 

OCL 

'lAu T 



(GAAH/^,GAJW»GCLnSE#iGOAPt,GERASr*,GLINENOff,GNCPl^f OOOOuOO^ 

GNijrilTS^^f GiJPLN#,GREAD*,GUM Ti^f GWAl T#,G WRl TE # ) CHA^^ ; OOOOroi-". 

G( E MT« Chak; 00i''){:c2^ 

GALL'/ CtHAk; OOOGOOy: 

= 'JCL GAAP ENTRY ( POl fUEK , P Jl NTEK , gOOuOOA ; 

FIXLD B1N(31)M; OOUOOO^J 

= 'OCL GAg ENTRY ( PUl NTbP ,CHAR ( 1) , Bl T ( U , OOOTOC-j-i 

FIXED hlN(3n, FIXED dIN(3IM«; 00r)00'»7: 

GCLOSE E.NTRY *( PJI NTE^^ ) • ; OOOOC'J>i'; 

GOAP ENTRY i POl N TER ,F 1 XbU lilNOlIM; 0(>0000'/; 

GL»^ASt ENTRY ( PU I NTEK ,CHAK( 1) VAP , Pul NTER , OOO'jO K".. 
FIXEU H1N(31), FIXED lilNCilM': OO'JOOlIO 

GLINFNO ENTRY (FIXEO 13IN(31)) 0000UI20 

RETURNS (CHAR(1))»; OOOOOlv; 
GMCP ENTRY (POINTER) RETURNS (FIXED BIN(31)I»; 00000140 

GNJMITS ENTRY(ChAR( 61) OOQUOl^^'/ 

RETURNS(FIXfciD B1N(31))»; 0000)1^': 

ENTRY (POINTER , CHAR (8) •CHAK(3)VAR, 0000017? 

CHAR(5) .FIXED B1N(31),, OOCOOI>^. 

FIXED BIN( 31)) »; OOOOOISc 

( PUINTE^^ ,LHAK(3) VAR,POINTEk, 0000020;; 

CHAK(*) VARfFlXED tilN(3I) , OJO0t2Lu 

FIXED HIN( 31)) »; 000002..'- 
GUNIT ENTRY(POINTER) kETURNS( FI XED BIN(Jl))«; OOOUt.2 "^w 

GWAIT ENTRY ( POl NTER ,F I XED B1N(31))'; OuOOO?^'- 

GnRITE ENTRY ( POI NTER •CHAR ( 3 ) VARt PO INTcP , OQOO^^I'^ 

CHAR(*)VAR, FIXED BIN<3I)f 0000:)>or- 

FIXLD B1N(31) ) »; 000CC27*.- 
GLbNTCHAR(l) STATIC IN1T(»» »»)•; • 0000(2rfO 

•GAAP'»;GAU#;GCLOSE^;GOAP*;GEKASfc#;GLINENQ#; OOOOOZ^M 

GUCP,v;GNUiMITS#;GUPENirf;GRFAD#;GUNl T#;GwAIT#; OOOCO iO- 

Gwh' ITt// ;GCENT»» ; 0000031'' 
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Figure 6. 
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DISPL/Y : PR(!C ftl»TIJ>JS<MAlNf; 
SoUkCt. I ISTING. 



STMT levC-L Nt-ST 

1 DISPLAY : Pf^UC llPTIfr4S(>^<iIN) ? I 

2 1 .>r.L (OCRPm»OACi*i»>TK,OC(.»ilMK) POIVTtR, 2 

CUM> hTT(l) , 3 

MMS*; CHA^^iP) VAP.YlNut 4 

i-^ HKCn ^IN(3l); 5 

i I OCL GOPtN -€MRY « PtII NTe R »CHAt^ (H ) » CHAR ( 3 ) VAP.» 7 I 

LlM*i(S) ,FIXCI) niN(3l),, 7 I 

HXtO E^n.M il)) ; 7 1 

^ 1 -)CL GAAP If^TPV (PaiNTthfPOUJTtK, B l 

riXFI) >UN(il) ) ; 8 1 

*> 1 OCL GrtOITF rr-JTKV ( Pill iMfPRf CHAW ( ^ ) VAk , PulNTEi^ , 9 1 

CIIAR( »)V4«,F1XP0 i3IN(3l), <) I 

J^IXFO "^iNiBl J > ; 9 1 

^ I '^CL TwJAIT fNT^Y (PlllNTt-^ ♦FlXirO UNO!)) ; 10 I 

r I 'JUL t;LliNrfV> t>:Tk>f <FIXM .3I'^t(3i)> U I 

JFri)PM<i (CitA'^d)) ; It I 

H 1 OCL fJA.^ £NT*?Y ( Pi)I >^TEK tCHAH ( 1 ) t J I f ( 1) ♦ 12 1 

nxtu BlN«il)fFixbn rtlNCU)) ; 12 1 

9 1 OCL '^KCAO cMkY (PnrfMTt«fC+lA^.(3)VA1^,P(JlNTE:^f 13 1 

CmAP»(*>VAw,F IXfcO r*lN(3l), 13 I 

F IXtO Hirjiil ) ) ; 13 1 

IC 1 OCL i:,rKA?;t 1>jT<v ( PtJI MT Fk fCHAK ( 1) VAK ♦ POlNTtK, 14 1 

riXrO HlN(Jl),FIxrf) bIN(31)) ; 14 1 

OCL GOAP *=N'TXY (POirjTEh fFIXFJ mIN(31)) ; 15 1 

OCL OCLOSfc tNfKY (POINTCK) ; 16 I 

OCL ^.CFNT CHAW(l) >TATIC TmITC M : 17 1 

CALL .VlPt T: (OC iPTH.^niSPS • I Of ♦ ♦ • UAS IC •» I f 0,H ) ; 18 

CALL ';aAP (GAC^)PT'<,0UDPTK,^); 19 

LiJ'iD : CALL O.^KlTl (OECHPTrttUASOCKPTR, 20 

GLINCNGdJ N 'RFAPY • | I GCFNT, I , H ) ; 21 

CALL G«&IT (f)tC3PTt^,H); 22 

CALL GAC (GACOPTK,*ViSC JNO,l,t*) ; 23 

CALL GWfAO (CLU^iPTi^f •^ •,l)C.JPTP,MIMSG,l,R); 24 

LALL GWAIT (OrCHPTKtHr; 25 

POT cOIT (i^lMSG) (SKIP, A); 26 

IF Mlf-ISG-ts'STUP' THF^4 CO TU LOOP; 2? 

CALL GFPASF ( Dt C liPTP t • • t DCrtPTH , 1 , M ) : 28 

CALL GV.AIT (ni.CrtPTRff); 29 

CALL GOAP iOAr-iPTK-tP) ; 30 

Call ^CLf.st (ncdPT^'J: 31 

rrvif); . 32 

nfum 7. 
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(4) At the stateioent labelled LOOP» the 

vrlteiQode argument to the CMRITE routine 
Is coded as '£A' to Indicate that a pre- 
vrlte screen erase Is to occur» followed 
by a line -addressed output operation. 
Hie GLINENO routine Is used to supply 
the proper line code for line 1 of the 
display. The variable GCENT Is used to 
supply the character code for the SIART 
symbol. The line vlll appear on the dis- 
play as 

READY ^ 

with the cursor Inynedlately to the right 
of the START symbol. 

' (5) The wait mode of the GAQ routine Is tised 

to wait for the appearance of an attention 
at the device. 

(6) The manual input mode of the OREAD routine 
Is used to cause the characters entered by 
the operator to be transferred to the string 
variable MIMSG. When the call Is made to 

^ wait; the current length of the varying 

string MI^SG Is set to the number of char- 
acters read from the device. The unit num- 
ber specified in the call to GREAD is 1 
(as it is in the calls to CMRITE and GAQ) 
because only one display is being serviced. 

♦. 

(7) When the program is complete, a call is 
made to GERASE to erase the screen, GDAF 
is called to terminate the processing of 

] attentions by the control program, and 

\ the graphics DCB is closed by a call to 

GCLOSE. 

i (8) In the linkedit step of the Jol\ a DD 

statement defining the library con- 
taining the GRASP routines must be 

I concatenated to the SYSLIB DD state- 

ment in the PLlLFCLG catalogued pro- 
cedure . 



24 



(9) In the go step of the job, a DD state- 
ment is Included defining the 2260 device. 
As coded in the exan^le, an available 2260 
will be allocated to the program. If more 
than one 2260 is desired, the following DD 
staten^nt may be used: 

//GO.DISP DD UNIT«(2260-l,n) 

where "n" is a decimal integer indicating 
the number of 2260 's desired. 
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